Fix assignment safety, roster parsing, and Ralph authority by bradygaster · Pull Request #2156 · github/squad

bradygaster · 2026-10-03T00:39:01Z

What

This PR makes squad-issue-assign.yml the sole Copilot assignment authority and fails visibly when its required token or assignment confirmation is missing. It also limits team roster parsing to supported roster sections and corrects Ralph's monitor-only merge-authority guidance. For #2085, it addresses only the misleading attribution of deterministic triage as Lead-agent analysis; it does not change routing policy or fully resolve that issue.

Why

Resolves #2080, #2079, and #2077. Partially addresses #2085 by making triage provenance explicit; #2085's other concerns remain out of scope.

How

Require COPILOT_ASSIGN_TOKEN before label-triggered routing/comment/assignment; reject failed or malformed API responses and distinguish API acceptance from a verified session handoff.
Remove heartbeat's competing Copilot assignment path while preserving monitoring and label triage.
Scope parseTeamMarkdown() to supported roster sections and cover the correct squad health count.
Clarify that Ralph monitors and reports, the coordinator verifies readiness and hands off, and only a human merges; sync canonical template mirrors.
Add executable workflow/parser/authority regressions and changesets for the shipped template and SDK changes.

⚠️ Quick Check

If SDK/CLI source files changed: completed the applicable Changeset step below (npx changeset add / .changeset/*.md, direct CHANGELOG.md entry for maintainers, or skip-changelog label for no user-facing changes)

PR Readiness Checklist

The PR readiness bot will validate these automatically after push.
Check each item before requesting review. See CONTRIBUTING.md for full details.

Branch & Commit

Branch created from dev (not main)
Branch is up to date with dev (git fetch upstream && git rebase upstream/dev) — not rechecked against the latest remote tip in this session
Verified diff contains only intended changes (git diff --cached --stat)
PR is not in draft mode (mark ready when checks pass)
Commit history is clean (squash fixups before review)

Build & Test

npm run build passes — blocked: SDK build reports tsc is unavailable after dependency restore failed on package-feed 404s
npm test passes (all tests green) — full suite not run; focused suites below
npm run lint passes (type check clean) — not run; dependencies unavailable
npm run lint:eslint passes — not run; dependencies unavailable
For migration PRs (>20 files): include test output summary in PR description

Focused results: node node_modules\vitest\vitest.mjs run test\assignment-safety-attribution.test.ts test\recast-identity-neutrality.test.ts --reporter=dot — 108 passed. node node_modules\vitest\vitest.mjs run test\migration.test.ts test\crlf-normalization.test.ts test\parser-contracts.test.ts test\type-extensions.test.ts test\cli\health-command.test.ts --reporter=dot — 147 passed. The Ralph authority Vitest test could not run because vitest was unavailable after the package restore failed; direct Node assertions passed against all five synchronized reference files and verified that the regression conditions detect the pre-fix merge instructions.

Changeset

Changeset added via npx changeset add / .changeset/*.md (if packages/squad-sdk/src/ or packages/squad-cli/src/ changed)
Or direct CHANGELOG.md entry (maintainers only — write-protected for external contributors)
Or skip-changelog label applied (if no user-facing changes)

Docs

README section updated (if new feature/module) — N/A
Docs feature page (if new user-facing capability) — updated Copilot coding-agent guidance

Exports

package.json subpath exports updated (if new module) — N/A; no new modules or exports

Breaking Changes

None.

Waivers

None requested; build/type/lint checks remain unverified due unavailable dependencies.

Closes #2080, Refs #2085 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Closes #2079 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-10-03T00:39:13Z

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 5305d64

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 2 item(s) to address before review

Status	Check	Details
❌	Single commit	5 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	⚠️ PR includes 1 .squad/ file(s) — ensure these are intentional
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	1 active Copilot thread(s) resolved (2 outdated skipped)
✅	CI passing	All checks passing

Files Changed (29 files, +1406 −870)

File	+/−
`.changeset/2079-team-roster-table-scope.md`	+5 −0
`.changeset/assignment-safety-attribution.md`	+6 −0
`.changeset/tidy-ralph-guidance.md`	+6 −0
`.github/workflows/squad-heartbeat.yml`	+21 −74
`.github/workflows/squad-issue-assign.yml`	+87 −57
`.github/workflows/squad-triage.yml`	+20 −16
`.squad-templates/ralph-reference.md`	+31 −25
`.squad-templates/workflows/squad-heartbeat.yml`	+21 −71
`.squad-templates/workflows/squad-issue-assign.yml`	+86 −56
`.squad-templates/workflows/squad-triage.yml`	+20 −16
`.squad/templates/ralph-reference.md`	+31 −25
`docs/src/content/docs/features/copilot-coding-agent.md`	+29 −17
`packages/squad-cli/templates/ralph-reference.md`	+31 −25
`packages/squad-cli/templates/workflows/squad-heartbeat.yml`	+21 −71
`packages/squad-cli/templates/workflows/squad-issue-assign.yml`	+86 −56
`packages/squad-cli/templates/workflows/squad-triage.yml`	+20 −16
`packages/squad-sdk/src/config/markdown-migration.ts`	+17 −3
`packages/squad-sdk/templates/ralph-reference.md`	+31 −25
`packages/squad-sdk/templates/workflows/squad-heartbeat.yml`	+21 −71
`packages/squad-sdk/templates/workflows/squad-issue-assign.yml`	+86 −56
`packages/squad-sdk/templates/workflows/squad-triage.yml`	+20 −16
`templates/ralph-reference.md`	+31 −25
`templates/workflows/squad-heartbeat.yml`	+21 −71
`templates/workflows/squad-issue-assign.yml`	+86 −56
`templates/workflows/squad-triage.yml`	+20 −16
`test/assignment-safety-attribution.test.ts`	+372 −0
`test/cli/health-command.test.ts`	+79 −6
`test/migration.test.ts`	+46 −0
`test/ralph-reference-authority.test.ts`	+55 −0

Total: +1406 −870

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

github-actions · 2026-10-03T00:39:14Z

⚠️ Squad File Leakage Detected

Authoritative evidence: base-controlled pull_request_target reporter.

The following .squad/ files were modified in this PR:

.squad/templates/ralph-reference.md

These files affect team routing, agent charters, and decisions.
If intentional, ensure approval from the team lead.

github-actions · 2026-10-03T00:39:15Z

🟠 Impact Analysis — PR #2156

Risk tier: 🟠 HIGH

📊 Summary

Metric	Count
Files changed	29
Files added	5
Files modified	24
Files deleted	0
Modules touched	8

🎯 Risk Factors

29 files changed (21-50 → HIGH)
8 modules touched (5-8 → HIGH)

📦 Modules Affected

ci-workflows (3 files)

.github/workflows/squad-heartbeat.yml
.github/workflows/squad-issue-assign.yml
.github/workflows/squad-triage.yml

docs (1 file)

docs/src/content/docs/features/copilot-coding-agent.md

root (7 files)

.changeset/2079-team-roster-table-scope.md
.changeset/assignment-safety-attribution.md
.changeset/tidy-ralph-guidance.md
templates/ralph-reference.md
templates/workflows/squad-heartbeat.yml
templates/workflows/squad-issue-assign.yml
templates/workflows/squad-triage.yml

squad-cli (4 files)

packages/squad-cli/templates/ralph-reference.md
packages/squad-cli/templates/workflows/squad-heartbeat.yml
packages/squad-cli/templates/workflows/squad-issue-assign.yml
packages/squad-cli/templates/workflows/squad-triage.yml

squad-sdk (5 files)

packages/squad-sdk/src/config/markdown-migration.ts
packages/squad-sdk/templates/ralph-reference.md
packages/squad-sdk/templates/workflows/squad-heartbeat.yml
packages/squad-sdk/templates/workflows/squad-issue-assign.yml
packages/squad-sdk/templates/workflows/squad-triage.yml

squad-state (1 file)

.squad/templates/ralph-reference.md

templates (4 files)

.squad-templates/ralph-reference.md
.squad-templates/workflows/squad-heartbeat.yml
.squad-templates/workflows/squad-issue-assign.yml
.squad-templates/workflows/squad-triage.yml

tests (4 files)

test/assignment-safety-attribution.test.ts
test/cli/health-command.test.ts
test/migration.test.ts
test/ralph-reference-authority.test.ts

This report is generated automatically for every PR. See #733 for details.

github-actions · 2026-10-03T00:39:15Z

🔒 Security Review

Authoritative evidence: base-controlled pull_request_target reporter.

🔒 Security review: 1 warning(s), 2 info.

Severity	Category	Finding	Location
🟡 warning	secrets-reference	Non-standard secret reference in workflow — verify this secret is necessary and scoped correctly.	`.github/workflows/squad-issue-assign.yml:32`
ℹ️ info	workflow-permissions	Workflow grants write permission — verify this is the minimum required scope.	`.github/workflows/squad-heartbeat.yml:35`
ℹ️ info	workflow-permissions	Workflow grants write permission — verify this is the minimum required scope.	`.github/workflows/squad-triage.yml:10`

Automated security review — informational only.

github-actions · 2026-10-03T00:39:17Z

🏗️ Architectural Review

Authoritative evidence: base-controlled pull_request_target reporter.

⚠️ Architectural review: 1 warning(s).

Severity	Category	Finding	Files
🟡 warning	sweeping-refactor	This PR touches 29 files (29 modified/added, 0 deleted). Large PRs are harder to review — consider splitting if possible.	—

Automated architectural review — informational only.

Copilot

🟡 Changes recommended

Automated assignment and roster compatibility regressions remain unresolved.

3 open findings

Parent-label repair can trigger conflicting assignment runs · New
Auto-assignment lacks a cross-workflow handoff · New
Preserve parsing for the legacy Team Roster heading · New

What changed in this PR

Improves Squad’s assignment safety, roster accuracy, and role guidance across active workflows, the SDK, and distributed templates.

Changes:

Consolidates workflow assignment checks and discloses deterministic triage provenance without redesigning routing.
Restricts roster parsing and adds parser, health, and workflow regressions.
Clarifies Ralph’s monitoring role and human merge authority, with synchronized templates and changesets.

File	Description
`test/ralph-reference-authority.test.ts`	Checks authority guidance and template synchronization.
`test/migration.test.ts`	Tests exclusion of auxiliary tables.
`test/cli/health-command.test.ts`	Updates mocks and roster-count regressions.
`test/assignment-safety-attribution.test.ts`	Tests assignment checks, provenance, and workflow mirrors.
`templates/workflows/squad-triage.yml`	Mirrors provenance and assignment delegation changes.
`templates/workflows/squad-issue-assign.yml`	Mirrors token and response checks.
`templates/workflows/squad-heartbeat.yml`	Removes competing assignment logic.
`templates/ralph-reference.md`	Mirrors monitoring and merge-authority guidance.
`packages/squad-sdk/templates/workflows/squad-triage.yml`	Ships updated triage behavior.
`packages/squad-sdk/templates/workflows/squad-issue-assign.yml`	Ships assignment safety checks.
`packages/squad-sdk/templates/workflows/squad-heartbeat.yml`	Removes SDK template’s competing assignment path.
`packages/squad-sdk/templates/ralph-reference.md`	Ships clarified authority guidance.
`packages/squad-sdk/src/config/markdown-migration.ts`	Limits table parsing to roster sections.
`packages/squad-cli/templates/workflows/squad-triage.yml`	Ships updated triage behavior.
`packages/squad-cli/templates/workflows/squad-issue-assign.yml`	Ships assignment safety checks.
`packages/squad-cli/templates/workflows/squad-heartbeat.yml`	Removes CLI template’s competing assignment path.
`packages/squad-cli/templates/ralph-reference.md`	Ships clarified authority guidance.
`docs/src/content/docs/features/copilot-coding-agent.md`	Explains assignment verification and triage provenance.
`.squad/templates/ralph-reference.md`	Updates installed authority guidance.
`.squad-templates/workflows/squad-triage.yml`	Updates canonical provenance and removes direct assignment.
`.squad-templates/workflows/squad-issue-assign.yml`	Adds canonical token and response validation.
`.squad-templates/workflows/squad-heartbeat.yml`	Removes canonical heartbeat assignment logic.
`.squad-templates/ralph-reference.md`	Defines canonical monitoring and human-merge guidance.
`.github/workflows/squad-triage.yml`	Updates active triage provenance and delegation.
`.github/workflows/squad-issue-assign.yml`	Adds active assignment checks and relocates label repair.
`.github/workflows/squad-heartbeat.yml`	Removes active heartbeat assignment logic.
`.changeset/tidy-ralph-guidance.md`	Records template guidance release notes.
`.changeset/assignment-safety-attribution.md`	Records assignment and provenance release notes.
`.changeset/2079-team-roster-table-scope.md`	Records SDK parser release notes.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

brady gaster and others added 3 commits October 2, 2026 17:22

fix: make Copilot assignment fail closed and disclose triage provenance

b0f54ca

Closes #2080, Refs #2085 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

fix(sdk): scope team markdown parsing

95b28d0

Closes #2079 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

docs: clarify Ralph merge authority (Closes #2077)

020173f

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

bradygaster requested a review from tamirdresher as a code owner October 3, 2026 00:39

Copilot AI balanced review requested due to automatic review settings October 3, 2026 00:39

Copilot started reviewing on behalf of bradygaster October 3, 2026 00:39

View session

Copilot AI reviewed Oct 3, 2026

View reviewed changes

Comment thread .github/workflows/squad-issue-assign.yml Resolved

Comment thread .squad-templates/workflows/squad-heartbeat.yml Resolved

Comment thread packages/squad-sdk/src/config/markdown-migration.ts Resolved

brady gaster and others added 2 commits October 2, 2026 18:02

fix: address assignment and roster review feedback

fa14b2e

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Merge branch 'dev' into bradygaster-assignment-safety-attribution

5305d64

bradygaster merged commit b127c7a into dev Oct 3, 2026
19 checks passed

Navigation Menu

Repository navigation

Fix assignment safety, roster parsing, and Ralph authority - #2156

Fix assignment safety, roster parsing, and Ralph authority#2156
bradygaster merged 5 commits into
devfrom
bradygaster-assignment-safety-attribution

bradygaster commented Oct 3, 2026

Uh oh!

github-actions Bot commented Oct 3, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 3, 2026

Uh oh!

github-actions Bot commented Oct 3, 2026

Uh oh!

github-actions Bot commented Oct 3, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

bradygaster commented Oct 3, 2026

What

Why

How

⚠️ Quick Check

PR Readiness Checklist

Branch & Commit

Build & Test

Changeset

Docs

Exports

Breaking Changes

Waivers

Uh oh!

github-actions Bot commented Oct 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛫 PR Readiness Check

⚠️ 2 item(s) to address before review

Files Changed (29 files, +1406 −870)

Uh oh!

github-actions Bot commented Oct 3, 2026

⚠️ Squad File Leakage Detected

Uh oh!

github-actions Bot commented Oct 3, 2026

🟠 Impact Analysis — PR #2156

📊 Summary

🎯 Risk Factors

📦 Modules Affected

Uh oh!

github-actions Bot commented Oct 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔒 Security Review

Uh oh!

github-actions Bot commented Oct 3, 2026

🏗️ Architectural Review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Oct 3, 2026 •

edited

Loading

github-actions Bot commented Oct 3, 2026 •

edited

Loading